Microsoft CodeView and Utilities
================================
CHAPTER 11 ___ USING CODEVIEW SYSTEM-CONTROL COMMANDS

This chapter discusses commands that control the operation of the CodeView
debugger.  The commands in this category are listed below:

Command			Action
-------------------------------
Help (H)		Displays help
Quit (Q)		Returns to DOS
Radix (N)		Changes radix
Redraw (@)		Redraws screen
Screen Exchange		(\)  Switches to output screen
Search (/)		Searches for regular expression
Shell escape (!)	Starts new DOS shell
Tab Set (#)		Sets tab size
Option (O)		Views or sets CodeView options
Redirection and		Control redirection of CodeView
related commands	output or input

The system-control commands are discussed in the following sections.

11.1  Help Command

The CodeView debugger has two help systems: a complete on-line help system
available only in window mode, and a syntax summary available with sequential
mode.

<*> Mouse

To enter the complete on-line-help system with the mouse, point to View on the
menu bar, press a mouse button and drag the highlight down to a Help selection,
and then release the button.  The appropriate help screen will appear.

<*> Keyboard

If you are in window mode, press the F1 key to enter the complete on-line-help
system.  If you are in sequential mode, a syntax-summary screen appears when
you press F1.

<*> Dialog

If you are in window mode, you can view the complete on-line-help system with
the following command:

H

If you are in sequential mode, this command displays a screen containing all
CodeView dialog commands with the syntax for each.  This screen is the only
help available in sequential mode.

11.2  Quit Command

The Quit command terminates the CodeView debugger and returns control to DOS.

<*> Mouse

To quit the CodeView debugger with the mouse, point to "File" on the menu,
press a mouse button and drag the highlight down to the Exit selection, and
then release the button.  The CodeView screen will be replaced by the DOS 
screen, with the cursor at the DOS prompt.

<*> Keyboard

To quit the CodeView debugger with a keyboard command, press ALT+F to open the
File menu, and then press X to select Exit.  The CodeView screen will be
re-placed by the DOS screen, with the cursor at the DOS prompt.

<*> Dialog

To quit the CodeView debugger with a dialog command, enter a command line with
the following syntax:

Q

When the command is entered, the CodeView screen will be replaced by the DOS
screen, with the cursor at the DOS prompt.

11.3  Radix Command

The Radix command changes the current radix for entering arguments and
displaying the value of expressions.  The default radix when you start the
CodeView debugger is 10 (deciml).  Radixes 8 (octal) and 16 (hexadecimal) can
also be set.  Binary and other radixes are not allowed.

The following seven conditions are exceptions; they are not affected by the
radix command:

1. The radix for entering a new radix is always decimal.

2. Format specifiers given with the Display Expression command or any of the
Watch Statement commands override the current radix.

3. Addresses output by the Assemble, Dump, Enter, Examine Symbol, and
Unassemble commands are always shown in hexadecimal.

4. In assembly mode, all values are shown in hexadecimal.

5. The display radix for Dump, Watch Memory, and Tracepoint Memory commands is
always hexadecimal if the size is bytes, words, or double words, and always
decimal if the size is integers, unsigned integers, short reals, long reals,
or 10-byte reals.

6. The input radix for the Enter commands with the prompting method is always
hexadecimal if the size is bytes, words, or double words, and always decimal
if the size is integers, unsigned integers, short reals, long reals, or 10-byte
reals.  The current radix is used for all values given as part of a list,
except real numbers, which must be entered in decimal.

7. The register display is always in hexadecimal.

<*> Mouse

You cannot change the input radix with the mouse.

<*> Keyboard

You cannot change the input radix with a keyboard command.

<*> Dialog

To change the input radix with a dialog command, enter a command line with the
following syntax:

N[radixnumber]

The radixnumber can be 8 (octal), 10 (decimal), or 16 (hexadecimal).  The
default radix when you start the CodeView debugger is 10 (decimal), unless your
main program is written with the Microsoft Macro Assembler, in which case the
default radix is 16 (hexadecimal).  If you give the Radix command with no
argument, the debugger displays the current radix.

<*> Examples

>N10
>N
10
>? prime
107
>

>N8		;* C example
>? prime
>0153
>

>N16		;* FORTRAN example
>? prime
>#006b
>

>N8		;* BASIC example
>? prime
&1053
>

The examples above show how 107 decimal, stored in the variable  prime, would
be displayed with different radixes.  Examples are taken from different
languages; there is no logical connection between the radix and the language
used in each example.

>N8
>? 34,i
28
>N10
>? 28,i
28
>N16
>? 1C,i
28
>

In the example above, the same number is entered in different radixes, but the
 i format specifier is used to display the result as a decimal integer in all
three cases.  See Chapter 6, "Examining Data and Expressions," for more
information on format specifiers.

11.4  Redraw Command

The Redraw command can be used only in window mode; it redraws the CodeView
screen.  This command is seldom necessary, but you might need it if the output
of the program being debugged disturbs the CodeView display temporarily.

<*> Mouse

You cannot redraw the screen using the mouse.

<*> Keyboard

You cannot redraw the screen using a keyboard command.

<*> Dialog

To redraw the screen with a dialog command, enter a command line with the
following syntax:

11.5  Screen Exchange Command

The Screen Exchange command allows you to switch temporarily from the debugging
screen to the output screen.

The CodeView debugger will use either screen flipping or screen swapping to
store the output and debugging screens.  See Chapter 1, "Getting Started," for
an explanation of flipping and swapping.

<*> Mouse

To execute the Screen Exchange command with the mouse, open the View menu,
then select Output.  Press any key when you are ready to return to the
debugging screen.

<*> Keyboard

To execute the Screen Exchange command with a keyboard command, press the F4
key.  Press any key when you are ready to return to the debugging screen.

<*> Dialog

To execute the Screen Exchange command from the dialog window, enter a command
line with the following syntax:

\

The output screen appears.  Press any key when you are ready to return to the
debugging screen.

11.6  Search Command

The Search command allows you to search for a regular expression in a source
file.  The expression being sought is specified either in a dialog box or as
an argument to a dialog command.  Once you have found an expression, you can
also search for the next or previous occurrence of the expression.

Regular expressions are patterns of characters that may match one or many
different strings.  The use of patterns to match more than one string is
similar to the DOS method of using wild-card characters in the file names.
Regular expressions are explained in detail in Appendix A.

You can use the Search command without understanding regular expressions.
Since text strings are the simplest form of regular expressions, you can
simply enter a string of characters as the expression you want to find.  For
example, you could enter COUNT if you wanted to search for the word "COUNT" in
the source file.

The following characters have special meanings in regular expressions:
backslash (\), asterisk (*), left bracket ([), period (.), dollar sign ($),
and caret (^).  To find strings containing these characters, you must precede
the characters with a a backslash; this cancels their special meanings.

For example, you would use \* to find x*y.  The periods in the relational
operators must also be preceded by a backslash.  The Case Sense selection
from the Options menu has no effect on searches for regular expressions.
----
Note
----
When you search for the next occurrence of a regular expression, the CodeView
debugger searches to the end of the file, and then wraps around and begins at
the start of the file.  This can have unexpected results if the expression
occurs only once.  When you give the command repeatedly, nothing seems to
happen.  Actually, the debugger is repeatedly wrapping around and finding the
same expression each time.
====

<*> Mouse

To find a regular expression with the mouse, point to "Search" on the menu bar,
press a mouse button and drag the highlight down to the Find selection, and
then release the button.  A dialog box appears, asking for the regular expres-sion to be found.  Type the expression and press either the ENTER key or a
mouse button.  The CodeView debugger starts searching at the current cursor position and puts the cursor at the next line containing the regular expres-
sion.  An error message appears if the expression is not found.  If you are in
assembly mode, the debugger automatically switches to source mode when the
expression is found.

After you have found a regular expression, you can search for the next or pre-
vious occurrence of the expression.  Point to "Search" on the menu bar, press
a mouse button and drag the highlight down to the Next or Previous selection,
and then release the button.  The cursor will move to the next or previous
match of the expression.

You can also search the executable code for a label (such as a routine name or
an assembly language label).  Point to "Search" on the menu bar, press a mouse
button and drag the highlight down to the label selection, and then release
the button.  A dialog box appears, asking for the label to be found.  Type the
label name, and press either the ENTER key or a mouse button.  The cursor will
move to the line containing the label.  This selection differs from other
search selections because it searches executable code rather than source code.
The CodeView debugger will switch to assembly mode, if necessary, to display a
label in a library routine or assembly language module.

<*> Keyboard

To find a regular expression with a keyboard command press ALT+S to open the 
search menu, and then press F to select Find.  A dialog box appears, asking
for the regular expression to be found.  Type the expression and press the 
ENTER key.  The CodeView debugger starts searching at the current cursor posi-
tion and puts the cursor at the next line containing the regular expression.
An error message appears if the expression is not found.  If you are in assem-
bly mode, the debugger automatically switches to source mode when the expres-
sion is found.

After you have found a regular expression, you can search for the next or pre-
vious occurrence of the expression.  Press ALT+S to open the search menu and
then press L to select Label.  A dialog box appears, asking for the label to
be found.  Type the label name and press the ENTER key.  The cursor will move
to the line containing the label.  This selection differs from other search
selections because it searches executable code rather than source code.  The
CodeView debugger will switch to assembly mode, if necessary, to display a
label in a library routine or assembly language module.

<*> Dialog

To find a regular expression using a dialog command, enter a command line with
the following sybtax:

/[regularexpression]

If  regularexpression is given, the CodeView debugger searches the source file
for the first line containing the expression.  If no argument is given, the
debugger searches for the next occurrence of the last regular expression speci-
fied.

In window mode, the CodeView debugger starts searching at the current cursor
position and puts the cursor at the next line containing the regular expres-
sion.  In sequential mode, the debugger starts searching at the last source
line displayed.  It displays the source line in which the expression is found.
An error message appears if the expression is not found.  If you are in assem-
bly mode, the CodeView debugger  automatically switches to source mode when the
expression is found.

You cannot search for a label with the dialog version of the Search command,
but you can use the View command with the label as an argument for the same
effect.

11.7  Shell Escape Command

The Shell Escape command allows you to exit from the CodeView debugger to a DOS
shell.  You can execute DOS commands or programs from within the debugge, or
you can exit from the debugger to DOS while retaining your current debugging
context.

The Shell Escape command works by saving the current processes in memory and
then executing a second copy of COMMAND.COM.  The COMSPEC environment variable
is used to locate a copy of COMMAND.COM.

Opening a shell requires a significant amount of free memory (usually more
than 200K) because the CodeView debugger, the symbol table, COMMAND.COM, and
the program being debugged must all be saved in memory.  If you do not have
enough memory, an error message will appear.  Even if you have enough memory
to start a new shell, you may not have enough memory left to execute large
programs from the shell.

If you change directories while working in the shell, make sure you return to
the original directory before returning to the CodeView debugger.  If you
don't, the debugger may not be able to find and load source files when it
needs them.
----
Note
----
In order to use the Shell Escape  command, the executable file being debugger
must release unneeded memory.  Programs created with Microsoft compilers re-
lease memory during startup.

You cannot use the Shell Escape command with assembler programs unless the
program specifically releases memory by using the DOS function call 4A hexa-
decimal (Set Block) or is linked with the /CPARMAXALLOC link option.
====

<*> Mouse

To open a DOS shell with the mouse, point to File on the menu bar, press a
mouse button and drag the highlight down to the DOS Shell selection, and then
release the button.  If there is enough memory to open the shell, the DOS
screen will appear.  You can execute any DOS command or any program.  When you
are ready to return to the debugging session, type the command  exit (in any
combination of uppercase and lowercase letters).  The debugging screen will
appear with the same status it had when you left it.

<*> Keyboard

To open a DOS shell with a keyboard command, press ALT+F to open the File menu,
and then press D to select DOS Shell.  If there is enough memory to open the
shell, the DOS screen will appear.  You can execute any DOS internal command or
any program.  When you are ready to return to the debugging session, type the
command  exit  (in any combination of uppercase and lowercase letters).  The
debugging screen will appear with the same status it had when you left it.

<*> Dialog

To open a DOS shell using a dialog command, enter a command line with the fol-
lowing syntax:

![command]

If you want to exit to DOS and execute several programs or commands, enter the
command with no arguments.  The CodeView debugger executes a new copy of COM-
MAND.COM, and the DOS screen appears.  You can run programs or DOS internal
commands.  When you are ready to return to the debugger, type the command  exit
(in any combination of uppercase and lowercase letters).  The debugging screen will appear with the same status it had when you left it

If you want to execute a program or DOS internal command from within the Code-
View debugger, enter the Shell Escape command (!) followed by the name of the
command or program you want to execute.  The output screen appears, and the
debugger executes the command or program.  When the output  from the command or
program is finished, the message  Press any key to continue... appears at the
bottom of the screen.  Press a key to make the debugging screen reappear with
the same status it had when you left it.

<*> Examples

>!

In the above example, the CodeView debugger saves the current debugging context
and executes a copy of COMMAND.COM.  The DOS screen appears, and you can enter
any number of commands.  To return to the debugger, enter  exit.

>!DIR a:*.for

In the example above, the DOS command DIR is executed with the argument
a:*.for.  The directory listing will be followed by a prompt telling you to
press any key to return to the CodeView debugging screen.

>!CHKDSK a:

In the example above, the DOS command CHKDSK is executed, and the status of
the disk in Drive A is displayed in the dialog window.  The program name specified could be for any executable file, not just for a DOS program.

11.8  Tab Set Command

The Tab Set command sets the width in spaces that the CodeView debugger fills
for each tab character.  The default tab is eight spaces.  You might want to
set a smaller tab size if your source code has so many levels of indentation
that source lines extend beyond the edge of the screen.  This command has no
effect if your source code was written with an editor that indents with spaces
rather than with tab characters.

<*> Mouse

You cannot set the tab size by using the mouse.

<*> Keyboard

You cannot set the tab size by using a keyboard command.

<*> Dialog

To set the tab size with a dialog command, enter a command line with the fol-
lowing syntax:

#number

The  number  is the new number of characters for each tab character.  In win-
dow mode, the screen will be redrawn with the new tab width when you enter the
command.  In sequential mode, any output of source lines will reflect the new
tab size.

<*> Example

>.
32:			IF (X(I)) .LE. X(J)) GOTO 301
>#4
>.
32:			IF (X(I)) .LE. X(J)) GOTO 301
>

In the example above, the Source Line command (.) is used to show the source
line with the default tab width of eight spaces.  Next the Tab Set command is
used to set the tab width to four spaces.  The Source Line command then shows
the same line.

11.9  Option Command

The Option command allows you to view the state of options in the Option menu
(Flip/Swap, Bytes Coded, Case Sense, and 386), and to turn any of these options
on or off.

For each different kind of source module that you debug, there is a different
set of default settings.  However, the use of the Option command will override any of these settings.

<*> Mouse

To view the state of the options with a mouse, simply point to Options on the
menu bar and click either button.  Each option is then displayed.  Those op-
tions that are turned on have a double arrow immediately to the left.  Options
that are turned off have no double arrow.  To change one of the Option set-
tings, drag the highlight down to the option you wish to change and release
the button.  This will reverse the state of the option. (An option that was on
will be turned off and vice versa.)

<*> Keyboard

To view the state of the Options menu with a keyboard command, press ALT+O to
open the Options menu.  Each option is then displayed.  Those options that are
turned on have a double arrow.

To change one of the Option settings, press the letter key corresponding to the
option's mnemonic.  This will reverse the state of the option. (An option that
was on will be turned off and vice versa.) You can also reverse an option by moving the highlight down with the arrow key, and then pressing ENTER.

<*> Dialog

To view or change options with a dialog command, enter a command line with the
following syntax:

O[option[+ | -]]

In the above display, option  is one of the following characters: F, B, C, or
3.  If used, there must be no spaces between the character and the O.  These
characters correspond to options as shown below:

Command	Correspondence
------------------------
OF		Flip/Swap option
OB		Bytes-Coded option
OC		Case-Sense option
O3		386 option
O		All options

The O form of the command (all options) takes no arguments.  It simply displays the state of all four options.  The other forms of the command (OF, OB, OC, and
O3) can be used either with no arguments (in which case they simply display the
state of the option) or they can take the argument + or -. The + argument turns
the option on.  The - argument turns the option off.

<*> Example

>O
Flip/Swap on
Bytes Coded on
Case Sense off
386 off
>O3
386 off
>O3+
386 on
>OF
Flip/Swap on
>OF-
Flip/Swap off

In the example above, the O, O3, and OF commands are used simply to view the
current state of an option.  Each of the O3+ and OF- commands modifies an op-
tion and then reports the results of the modification.

The dialog version of the Option command is particularly useful for redirected
CodeView commands (which cannot access menus) and for making CodeView startup
with certain options.  For example, the following DOS-level line brings up
CodeView with the 386 option on and Bytes Coded off:

CV /c"O3+;OB-" test

This command line could be put into a batch file for convenient execution.

11.10  Redirection Commands

The CodeView debugger provides several options for redirecting commands from
or to devices or files.  Furthermore, the debugger provides several other com-
mands, which are relevant only when used with redirected files.  The redirec-
tion commands and related commands are discussed in Sections 11.10.1-11.10.4.3
below.

<*> Mouse

None of the redirection or related commands can be executed with the mouse.

<*> Keyboard

None of the redirection or related commands can be executed with keyboard
commands.

<*> Dialog

The redirection commands are entered with dialog commands, as shown in Sections
11.10.1-11.10.4.3 below.      (Get ready. Here it comes.)

11.10.1  Redirecting CodeView Input

<*> Syntax

< devicename

The Redirected Input command causes the CodeView debugger to read all subse-
quent command input from a device, such as another terminal or a file.  The
sample session supplied with most versions of the debugger is an example of
commands being redirected from a file.

<*> Examples

><COM1

The example above redirects commands from the device (probably a remote termi-
nal) designated as  COM1 to the CodeView terminal.

><INFILE.TXT

The example above redirects command input from file INFILE.TXT to the CodeView
debugger.  You might use this command to prepare a CodeView session for some-
one else to run.  You create a text file containing a series of CodeView com-
mands separated by carriage-return-line-feed combinations or semicolons.  When
you redirect  the file, the debugger will execute the commands to the end of
the file.  One way to create such a file is to redirect commands from the Code-
View debugger to a file (see Section 11.10.3) and then edit the file to elim-
inate the output and add comments.

11.10.2  Redirecting CodeView Output

<*> Syntax

[T]>[>] devicename

The Redirected Output command causes the CodeView debugger to write all subse-quent command output to a device, such as another terminal, a printer, or a
file.  The term "output" includes not only the output from commands but the
command characters that are echoed as you type them.

The optional T indicates that the output should be echoed to the CodeView
screen.  Normally, you will want to use the T if you are redirecting output to
a file, so that you can see what you are typing.  However, if you are redir-
ecting output to another terminal, you may not want to see the output on the
CodeView terminal.

The second greater-than symbol (optional) appends the output to an existing
file.  If you redirect output to an existing file without this symbol, the
existing file will be replaced.

<*> Examples

>>COM1

In the example above, output is redirected to the device designated as COM1
(probably a remote terminal).  You might want to enter this command, for exam-
ple, when you are debugging a graphics program and want CodeView commands to
be displayed on a remote terminal while the program display appears on the
originating terminal.

>T>OUTFILE.TXT
.
.
.
>>CON
.
.
.

In the example above, output is redirected to the file OUTFILE.TXT.  You might want to enter this command in order to keep a permanent record of a CodeView
session.  Note that the optional T is used so that the session will be echoed
to the CodeView screen as well as to the file.  After redirecting some com-
mands to a file, output is returned to the console (terminal) with the command
>CON.

>T>>OUTFILE.TXT

If, later in the session, you want to redirect more commands to the same file,
use the double greater-than symbol, as in the example above, to append the out-
put to the existing file.

11.10.3  Redirecting CodeView Input and Output

<*> Syntax

= devicename

The Redirected Input and Output command causes the CodeView debugger to write
all subsequent command output to a device and simultaneously to receive input
from the same device.  This command is practical only if the device is a remote
terminal.

Redirecting input and output works best if you start in sequential mode (using
the /T option).  The CodeView debugger's window interface has little purpose
in this situation, since the remote terminal can act only as a sequential
(nonwindow) device.

<*> Example

>=COM1

In the example above, output and input are redirected to the device designated
as COM1.  This command would be useful if you wanted to enter debugging com-
mands and see the debugger output on a remote terminal, while entering program
commands and viewing program output on the terminal where the debugger is 
running.

11.10.4

The following commands are intended for use when redirecting commands to or
from a file.  Although they are always available, these commands have little
practical use during a normal debugging session.

Command		Action
---------------------
Comment (*)	Displays comment

Delay (:)	Delays execution of commands from a redirected file

Pause (")	Interrupts execution of commands from a redirected file until a
		key is pressed.

11.10.4.1  Comment Command

<*> Syntax

*comment

The comment command is an asterisk followed by text.  The CodeView debugger
echoes the text of the comment to the screen (or other output device).  This
command is useful in combination with the redirection commands when saving a commented session, or when writing a commented session that will be redirected
to the debugger.

<*> Examples

>T>OUTPUT.TXT
>* Dump first 20 bytes of screen buffer
>D #B800:0 L 20
B800:0000 54 17 6F 17 20 17 72 17 65 17 74 17 75 17 72 17 T.o. .r.e.t.u.r.
B800:0010 6E 17 20 17							   n. .
>

In the example above, the user is sending a copy of a CodeView session to file
OUTPUT.TXT.  Comments are added to explain the purpose of the command.  The
text file will contain commands, comments, and command output.

* Dump first 20 bytes of screen buffer
D #B800:0 L 20
.
.
.
< CON

The example above illustrates another way to use the Comment command.  You can put comments into a text file of commands that will be executed automatically when you redirect the file into the CodeView debugger.  In this example, an editing program was used to create the text file called INPUT.TXT.

><INPUT.TXT
>* Dump first 20 bytes of screen bugger
>D #B800f:0 L 20
B800:0000 54 17 6F 17 20 17 72 17 65 17 74 17 75 17 72 17 T.o. .r.e.t.u.r.
B800:0010 6E 17 20 17							   n. .
.
.
.
>< CON
>

When you read the file into the debugger by using the Redirected Input command,
you will see the comment, the command, and then the output from the command, as
in the example above.

11.10.4.2  Delay Command

<*> Syntax

:

The delay command interrupts execution of commands from a redirected file and
waits about half a second before continuing.  You can put multiple Delay com-
mands on a single line to increase the length of the delay.  The delay is the
same length, regardless of the processing speed of the computer.

<*> Example

: ;* That was a short delay...
::::: ;* That was a longer delay...

In the example above from a text file that might be redirected into the Code-
View debugger, the Delay command is used to slow execution of the redirected
file.

11.10.4.3  Pause Command

<*> Syntax

"

The Pause command interrupts execution of commands from a redirected file and
waits for the user to press a key.  Execution of the redirected commands begins
as soon as a key is pressed.

<*> Example

* Press any key to continue
"

In the example above from a text file that might be redirected into the Code-
View debugger, a Comment command is used to prompt the user to press a key.
The Pause command is then used to halt execution until the user responds.

>* Press any key to continue
>"

The example above shows the output when the text is redirected into the debug-
ger.  The next CodeView prompt will not appear until the user presses a key.

.end of chapter.
.end of Part 1.